Reorganization of Configuration Documentation
Information Architecture and Technical Writing for ESLint
ESLint is one of the most widely used linting software, known primarily for its configurable nature. Prior to this project, the configuration documentation of ESLint provided a lot of information on a single webpage. The content needed to be reorganized and edited so as to make it more usable and useful.
This project was completed over a period of three months (September to November 2020) under Google Season of Docs 2020. The purpose of this project was to identify the issues with the existing configuration documentation, propose solutions to the problems, and to improve both the quality and the presentation of the documentation.
Objectives
- To conduct a comprehensive content audit
- To understand the flow of information by creating an Information Architecture
- To reorganize the information by proposing a new Information Architecture
- To rewrite and edit parts of the documentation, as needed
- To ensure that the content is flexible and reusable
Project Phases
The project was completed in three phases, starting from an analysis of the existing content to editing and improving the documentation.
Phase 1: Content Audit and Analysis
In the first phase of the project, I conducted a comprehensive content audit of the existing configuration documentation of ESLint was conducted. The purpose of the content audit was to understand the content and its organization on the “Configuring ESLint” webpage. This understanding was taken a step ahead by highlighting major issues that could then be targeted in the next phases of the project.
Phase 2: Information Architecture
In the second phase, I created a new, improved, Information Architecture (IA) of the ESLint configuration documentation. The aim of this new IA was to reorganize and present the knowledge network in a more understandable way. Findings of the content audit, along with a study of the current IA, helped in highlighting the issues and presenting a better IA so as to resolve the problems in the current configuration documentation
Proposed information architecture for ESLint
Phase 3: Rewriting and Editing
In the third and final phase of the project, all the information obtained from the first two phases was used to improve, edit, and reorganize ESLint’s configuration documentation. Throughout this phase, care was taken that the documentation is accurate, updated, flexible, and reusable. The entire documentation was edited and organized using markdown and was then uploaded on GitHub, creating a Pull Request.
Features of New Documentation
The project succeeded in meeting its goals and was included in the list of successful projects released by Google. Some of the important features of the new configuration documentation were as follows.
- The new documentation was organized into six distinct sections, each dealing with a particular theme
- The documentation was on multiple webpages, thus improving the navigation and usability of the documentation
- The new documentation was organized into six distinct sections, each dealing with a particular theme
- The documentation was on multiple webpages, thus improving the navigation and usability of the documentation
- New links were added to the documentation to make up for the missing link
- The editing process ensured consistency and coherence in the configuration documentation
Summary
To keep track of the project’s progress, Issue #13632 was created on ESLint’s GitHub channel. Based on the findings of all the phases, the improved version of the documentation was uploaded under Pull Request #13837 on GitHub. Once all the comments were resolved, the old configuration documentation was deleted, replaced by the edited and reorganized version.
